﻿#region Copyright (c) 2012-10, Olaf Kober <amarok.projects@gmail.com>
//================================================================================
//	Permission is hereby granted, free of charge, to any person obtaining a copy
//	of this software and associated documentation files (the "Software"), to deal
//	in the Software without restriction, including without limitation the rights
//	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//	copies of the Software, and to permit persons to whom the Software is
//	furnished to do so, subject to the following conditions:
//
//	The above copyright notice and this permission notice shall be included in
//	all copies or substantial portions of the Software.
//
//	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//	THE SOFTWARE.
//================================================================================
#endregion

using System;
using System.Globalization;
using System.Runtime.Serialization;
using System.Security.Permissions;


namespace Amarok
{
	/// <summary>
	/// This exception type represents a failure.
	/// 
	/// "Failure refers to the state or condition of not meeting a desirable or intended objective, and may be 
	/// viewed as the opposite of success." (Source: http://en.wikipedia.org/wiki/Failure)
	/// 
	/// To uniquely identify failures each failure is represented by a unique failure number that consists of a 
	/// facility code (higher word) and a failure code (lower word). The facility code is used to indicate to 
	/// which facility (subsystem) the failure belongs. The failure code is a sequential number that is unique 
	/// per facility.
	/// </summary>
	[Serializable]
	public class FailureException : Exception
	{
		// data
		private readonly Int32 mFailureNumber;
		private readonly Object[] mArguments;


		#region ++ Public Interface ++

		/// <summary>
		/// Gets the failure number that indicates the failure. The failure number is a combination of the 
		/// facility code (upper word) and the failure code for that facility (lower word).
		/// </summary>
		public Int32 FailureNumber
		{
			get
			{
				return mFailureNumber;
			}
		}

		/// <summary>
		/// Gets the facility code (upper word) of the failure number. The facility code indicates to which
		/// facility (subsystem) the failure belongs.
		/// </summary>
		public Int32 FacilityCode
		{
			get
			{
				return Helper.GetHighWord(mFailureNumber);
			}
		}

		/// <summary>
		/// Gets the failure code (lower word) of the failure number. The failure code is a unique number in 
		/// the context of the facility (subsystem).
		/// </summary>
		public Int32 FailureCode
		{
			get
			{
				return Helper.GetLowWord(mFailureNumber);
			}
		}

		/// <summary>
		/// Gets an optional list of arguments that add information to this specific failure.
		/// </summary>
		public Object[] Arguments
		{
			get
			{
				return mArguments;
			}
		}

		/// <summary>
		/// Gets a message that describes the current exception.
		/// </summary>
		/// 
		/// <returns>
		/// The error message that explains the reason for the exception.</returns>
		public override String Message
		{
			get
			{
				return this.ToString();
			}
		}


		/// <summary>
		/// Initializes a new instance.
		/// </summary>
		/// 
		/// <param name="failureNumber">
		/// The failure number that indicates the failure. The failure number is a combination of the 
		/// facility code (upper word) and the failure code for that facility (lower word).</param>
		/// <param name="arguments">
		/// An optional list of arguments that add information to this specific failure.</param>
		public FailureException(Int32 failureNumber, params Object[] arguments)
			: this(failureNumber, null, arguments)
		{
		}

		/// <summary>
		/// Initializes a new instance.
		/// </summary>
		/// 
		/// <param name="failureNumber">
		/// The failure number that indicates the failure. The failure number is a combination of the 
		/// facility code (upper word) and the failure code for that facility (lower word).</param>
		/// <param name="innerException">
		/// The exception that is the cause of the current failure, or a null reference.</param>
		/// <param name="arguments">
		/// An optional list of arguments that add information to this specific failure.</param>
		public FailureException(Int32 failureNumber, Exception innerException, params Object[] arguments)
			: base(null, innerException)
		{
			mFailureNumber = failureNumber;
			mArguments = arguments;
		}


		/// <summary>
		/// Initializes a new instance.
		/// </summary>
		/// 
		/// <param name="facilityCode">
		/// The facility code (upper word) of the failure number. The facility code indicates to which
		/// facility (subsystem) the failure belongs.</param>
		/// <param name="failureCode">
		/// The failure code (lower word) of the failure number. The failure code is a unique number in 
		/// the context of that facility (subsystem) that indicated this failure.</param>
		/// <param name="arguments">
		/// An optional list of arguments that add information to this specific failure.</param>
		public FailureException(Int32 facilityCode, Int32 failureCode, params Object[] arguments)
			: this(facilityCode, failureCode, null, arguments)
		{
		}

		/// <summary>
		/// Initializes a new instance.
		/// </summary>
		/// 
		/// <param name="facilityCode">
		/// The facility code (upper word) of the failure number. The facility code indicates to which
		/// facility (subsystem) the failure belongs.</param>
		/// <param name="failureCode">
		/// The failure code (lower word) of the failure number. The failure code is a unique number in 
		/// the context of that facility (subsystem) that indicated this failure.</param>
		/// <param name="innerException">
		/// The exception that is the cause of the current failure, or a null reference.</param>
		/// <param name="arguments">
		/// An optional list of arguments that add information to this specific failure.</param>
		public FailureException(Int32 facilityCode, Int32 failureCode, Exception innerException, params Object[] arguments)
			: base(null, innerException)
		{
			mFailureNumber = Helper.MakeDWord(facilityCode, failureCode);
			mArguments = arguments;
		}


		/// <summary>
		/// Initializes a new instance.
		/// </summary>
		/// 
		/// <param name="exception">
		/// A failure exception that should be wrapped into a new failure exception to preserve the 
		/// original stack trace.</param>
		/// 
		/// <exception cref="ArgumentNullException">
		/// A null reference was passed to a method that did not accept it as a valid argument.</exception>
		public FailureException(FailureException exception)
			: base(null, exception)
		{
			Verify.NotNull(exception, "exception");

			mFailureNumber = exception.FailureNumber;
			mArguments = exception.Arguments;
		}


		/// <summary>
		/// Returns a string that represents the current FailureException instance.
		/// </summary>
		/// 
		/// <returns>
		/// A string that represents the current FailureException instance.</returns>
		public override String ToString()
		{
			return String.Format(CultureInfo.InvariantCulture,
				"FailureException(FailureNumber: 0x{0:X8}, Arguments: {1})",
				mFailureNumber,
				mArguments.AsString(";")
			);
		}

		#endregion

		#region ++ Serialization Interface ++

		/// <summary>
		/// Initializes a new instance.
		/// </summary>
		/// 
		/// <param name="info">
		/// The object that holds the serialized object data.</param>
		/// <param name="context">
		/// The contextual information about the source or destination.</param>
		/// 
		/// <exception cref="ArgumentNullException">
		/// A null reference was passed to a method that did not accept it as a valid argument.</exception>
		protected FailureException(SerializationInfo info, StreamingContext context)
			: base(info, context)
		{
			mFailureNumber = info.GetInt32("FailureNumber");
			mArguments = (Object[])info.GetValue("Arguments", typeof(Object[]));
		}

		/// <summary>
		/// The method sets the SerializationInfo with information about the exception.
		/// </summary>
		/// 
		/// <param name="info">
		/// The object that holds the serialized object data.</param>
		/// <param name="context">
		/// The contextual information about the source or destination.</param>
		/// 
		/// <exception cref="ArgumentNullException">
		/// A null reference was passed to a method that did not accept it as a valid argument.</exception>
		[SecurityPermission(SecurityAction.Demand, SerializationFormatter = true)]
		public override void GetObjectData(SerializationInfo info, StreamingContext context)
		{
			base.GetObjectData(info, context);

			info.AddValue("FailureNumber", mFailureNumber);
			info.AddValue("Arguments", mArguments, typeof(Object[]));
		}

		#endregion

	}
}
